home *** CD-ROM | disk | FTP | other *** search
/ IRIX Installation Tools & Overlays 1999 May / SGI IRIX Installation Tools & Overlays 1999 May - Disc 2.iso / relnotes / dmedia_dev / ch05.z / ch05
Text File  |  1999-04-19  |  22KB  |  331 lines
  1.  
  2.  
  3.  
  4.                                   - 1 -
  5.  
  6.  
  7.  
  8.        5.  _A_u_d_i_o__L_i_b_r_a_r_y
  9.  
  10.        This chapter lists information about the IRIS Audio Library
  11.        (AL) 2.0 programming interface included in the IRIS Digital
  12.        Media Development Environment.  It includes changes,
  13.        additions, and bug fixes since the IRIX 6.2, 6.3, and 6.4
  14.        releases, known problems, workarounds, and caveats.
  15.  
  16.        The IRIS Audio Library 2.0 is a C language library that
  17.        provides basic audio I/O, hardware control and
  18.        synchronization capabilities to applications.
  19.  
  20.        The Audio Library is shipped as a dynamic shared library
  21.        (generally /_u_s_r/_l_i_b/_l_i_b_a_u_d_i_o._s_o) included with IRIX 6.5.
  22.  
  23.        At the time of this release, the _I_R_I_S _D_i_g_i_t_a_l _M_e_d_i_a
  24.        _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e contains a description of the previous
  25.        version of the AL (1.0). AL 1.0 programs will continue to
  26.        work on AL 2.0-equipped systems. Most of the concepts are
  27.        quite similar between the two AL versions, so the _D_i_g_i_t_a_l
  28.        _M_e_d_i_a _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e remains a valuable reference. We
  29.        intend to update this programming guide at the earliest
  30.        opportunity.
  31.  
  32.        The on-line manual page _A_L_i_n_t_r_o(_3_d_m) contains a short
  33.        overview of AL 2.0 library functionality and a complete list
  34.        of the procedure calls.  Manual pages for both AL 2.0 calls
  35.        and AL 1.0 calls are included.  The man pages _a_l_R_e_s_o_u_r_c_e_s
  36.        aaaannnndddd _a_l_P_a_r_a_m_s wwwwiiiillllllll aaaallllssssoooo bbbbeeee qqqquuuuiiiitttteeee uuuusssseeeeffffuuuullll....
  37.  
  38.        5555....1111  _C_h_a_n_g_e_s__a_n_d__A_d_d_i_t_i_o_n_s
  39.  
  40.        IRIX 6.3 introduced a new version of the Audio Library (AL
  41.        2.0).  This version remains backwards-compatible with
  42.        previous versions of the Audio Library; all the older AL
  43.        functions are provided and supported. However, a new set of
  44.        function calls are included in the library. This section
  45.        provides an overview of the features available with the new
  46.        calls. Several new features have been added in IRIX 6.5.
  47.  
  48.           +o AL 2.0 calls conform to the OpenGL capitalization
  49.             conventions. For example, the new version of
  50.             _A_L_o_p_e_n_p_o_r_t() is called _a_l_O_p_e_n_P_o_r_t().
  51.  
  52.           +o AL 2.0 calls all use units of sample frames. This is
  53.             consistent with the other digital media libraries.
  54.             Where necessary, the new AL function call names have
  55.             been changed to indicate this; for example, the new
  56.             equivalent of _A_L_w_r_i_t_e_s_a_m_p_s() is called _a_l_W_r_i_t_e_F_r_a_m_e_s().
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                                   - 2 -
  71.  
  72.  
  73.  
  74.           +o The AL 2.0 audio driver supports multiple independent
  75.             audio input and output devices on the same system.
  76.             Applications written with AL 2.0 can address multiple
  77.             devices simultaneously. Old AL applications can address
  78.             only the default input device and default output
  79.             device.  These devices can be set via _a_p_a_n_e_l, or by any
  80.             AL 2.0 application.  See the _a_l_P_a_r_a_m_s man page for
  81.             information on default devices.
  82.  
  83.           +o The AL 2.0 audio driver maintains independent gain
  84.             values for each input source. This means users seldom
  85.             need to adjust the input gain when changing input
  86.             sources.  Now when a user selects a new input source,
  87.             the gain will automatically revert to its value when
  88.             that source was previously selected.
  89.  
  90.           +o AL 2.0 provides a scalable, device-independent hardware
  91.             control model. Parameter/value lists and the functions
  92.             which use them have changed substantially. See the
  93.             _a_l_P_a_r_a_m_s, _a_l_S_e_t_P_a_r_a_m_s, and _a_l_G_e_t_P_a_r_a_m_s man pages for
  94.             more information.
  95.  
  96.           +o AL 2.0 introduces new functions for writing zero-valued
  97.             sample-frames (_a_l_Z_e_r_o_F_r_a_m_e_s(_3_d_m)) and for discarding
  98.             sample-frames from an input or output port
  99.             (_a_l_D_i_s_c_a_r_d_F_r_a_m_e_s(_3_d_m)). The latter function satisfies
  100.             request-for-enhancement (RFE) 374702.
  101.  
  102.           +o AL 2.0 removes the minimum queuesize limit (see
  103.             _a_l_S_e_t_Q_u_e_u_e_S_i_z_e(_3_d_m)). This satisfies RFE 158615.
  104.  
  105.           +o IRIX 6.5 adds support for asynchronous event handling.
  106.             You can now have the AL notify your application when
  107.             parameters change; polling is no longer necessary. See
  108.             _a_l_I_n_t_r_o(_3_d_m) ffffoooorrrr aaaa lllliiiisssstttt ooooffff eeeevvvveeeennnntttt ffffuuuunnnnccccttttiiiioooonnnnssss....
  109.  
  110.           ++++oooo IIIIRRRRIIIIXXXX 6666....5555 aaaaddddddddssss ssssuuuuppppppppoooorrrrtttt ffffoooorrrr ddddiiiiggggiiiittttaaaallll aaaauuuuddddiiiioooo ssssuuuubbbbccccooooddddeeee....
  111.             SSSSuuuubbbbccccooooddddeeee iiiissss pppprrrreeeesssseeeennnntttteeeedddd aaaassss aaaannnn aaaaddddddddiiiittttiiiioooonnnnaaaallll ddddaaaattttaaaa ffffoooorrrrmmmmaaaatttt ffffoooorrrr
  112.             aaaauuuuddddiiiioooo;;;; wwwwrrrriiiittttiiiinnnngggg aaaannnndddd rrrreeeeaaaaddddiiiinnnngggg iiiitttt iiiissss vvvveeeerrrryyyy ssssiiiimmmmiiiillllaaaarrrr ttttoooo
  113.             wwwwrrrriiiittttiiiinnnngggg aaaannnndddd rrrreeeeaaaaddddiiiinnnngggg aaaauuuuddddiiiioooo ddddaaaattttaaaa.... SSSSeeeeeeee _a_l_S_e_t_S_a_m_p_F_m_t(_3_d_m)
  114.             aaaannnndddd _a_l_R_e_a_d_F_r_a_m_e_s(_3_d_m) aaaannnndddd _a_l_W_r_i_t_e_F_r_a_m_e_s(_3_d_m) ffffoooorrrr mmmmoooorrrreeee
  115.             iiiinnnnffffoooorrrrmmmmaaaattttiiiioooonnnn.... IIIInnnn aaaaddddddddiiiittttiiiioooonnnn ttttoooo tttthhhheeee AAAALLLL ccccaaaallllllllssss,,,, tttthhhheeee AAAAuuuuddddiiiioooo
  116.             CCCCoooonnnnttttrrrroooollll PPPPaaaannnneeeellll pppprrrroooovvvviiiiddddeeeessss ssssuuuuppppppppoooorrrrtttt ffffoooorrrr sssswwwwiiiittttcccchhhhiiiinnnngggg bbbbeeeettttwwwweeeeeeeennnn
  117.             ccccoooonnnnssssuuuummmmeeeerrrr----mmmmooooddddeeee aaaannnndddd pppprrrrooooffffeeeessssssssiiiioooonnnnaaaallll----mmmmooooddddeeee ssssuuuubbbbccccooooddddeeee....
  118.  
  119.           ++++oooo IIIIRRRRIIIIXXXX 6666....5555 aaaaddddddddssss ffffuuuunnnnccccttttiiiioooonnnnssss ffffoooorrrr eeeeffffffffiiiicccciiiieeeennnnttttllllyyyy rrrreeeeaaaaddddiiiinnnngggg aaaannnndddd
  120.             wwwwrrrriiiittttiiiinnnngggg nnnnoooonnnn----iiiinnnntttteeeerrrrlllleeeeaaaavvvveeeedddd,,,, oooorrrr fffflllleeeexxxxiiiibbbbllllyyyy iiiinnnntttteeeerrrrlllleeeeaaaavvvveeeedddd,,,, ddddaaaattttaaaa....
  121.             SSSSeeeeeeee tttthhhheeee mmmmaaaannnn ppppaaaaggggeeeessss _a_l_W_r_i_t_e_B_u_f_f_e_r_s(_3_d_m) aaaannnndddd
  122.             _a_l_R_e_a_d_B_u_f_f_e_r_s(_3_d_m)....  TTTThhhheeeeyyyy aaaalllllllloooowwww yyyyoooouuuu ttttoooo rrrreeeeaaaadddd oooorrrr wwwwrrrriiiitttteeee
  123.             aaaannnnyyyy nnnnuuuummmmbbbbeeeerrrr ooooffff bbbbuuuuffffffffeeeerrrrssss ooooffff aaaarrrrbbbbiiiittttrrrraaaarrrryyyy nnnnuuuummmmbbbbeeeerrrrssss ooooffff cccchhhhaaaannnnnnnneeeellllssss
  124.             ffffrrrroooommmm aaaa ppppoooorrrrtttt....  TTTThhhheeeesssseeee ffffuuuunnnnccccttttiiiioooonnnnssss wwwwiiiillllllll bbbbeeee uuuusssseeeeffffuuuullll iiiiffff yyyyoooouuuu
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.                                   - 3 -
  137.  
  138.  
  139.  
  140.             wwwwaaaannnntttt ttttoooo ddddoooo tttthhhhiiiinnnnggggssss lllliiiikkkkeeee wwwwrrrriiiitttteeee 22224444 1111----cccchhhhaaaannnnnnnneeeellll bbbbuuuuffffffffeeeerrrrssss
  141.             aaaaccccrrrroooossssssss 3333 8888----cccchhhhaaaannnnnnnneeeellll ppppoooorrrrttttssss,,,, oooorrrr jjjjuuuusssstttt rrrreeeeaaaadddd cccchhhhaaaannnnnnnneeeellllssss 3333,,,,4444,,,,5555,,,,
  142.             aaaannnndddd 6666 ooooffff aaaannnn 8888----cccchhhhaaaannnnnnnneeeellll ppppoooorrrrtttt,,,, oooorrrr wwwwrrrriiiitttteeee tttthhhheeee ssssaaaammmmeeee mmmmoooonnnnoooo
  143.             bbbbuuuuffffffffeeeerrrr aaaaccccrrrroooossssssss aaaallllllll tttthhhheeee cccchhhhaaaannnnnnnneeeellllssss ooooffff aaaa ppppoooorrrrtttt....
  144.  
  145.           ++++oooo IIIIRRRRIIIIXXXX 6666....5555 aaaaddddddddssss tttthhhheeee aaaabbbbiiiilllliiiittttyyyy ttttoooo ttttuuuurrrrnnnn ooooffffffff lllliiiimmmmiiiittttiiiinnnngggg oooonnnn
  146.             ffffllllooooaaaattttiiiinnnngggg----ppppooooiiiinnnntttt ttttoooo iiiinnnntttteeeeggggeeeerrrr ccccoooonnnnvvvveeeerrrrssssiiiioooonnnn wwwwiiiitttthhhhiiiinnnn tttthhhheeee AAAAuuuuddddiiiioooo
  147.             LLLLiiiibbbbrrrraaaarrrryyyy ((((uuuusssseeeedddd wwwwhhhheeeennnn yyyyoooouuuu uuuusssseeee tttthhhheeee AAAALLLL____SSSSAAAAMMMMPPPPFFFFMMMMTTTT____FFFFLLLLOOOOAAAATTTT oooorrrr
  148.             AAAALLLL____SSSSAAAAMMMMPPPPFFFFMMMMTTTT____DDDDOOOOUUUUBBBBLLLLEEEE oooouuuuttttppppuuuutttt ddddaaaattttaaaa ttttyyyyppppeeeessss)))).... IIIIffff yyyyoooouuuu kkkknnnnoooowwww tttthhhhaaaatttt
  149.             yyyyoooouuuurrrr ffffllllooooaaaattttiiiinnnngggg----ppppooooiiiinnnntttt oooouuuuttttppppuuuutttt ddddaaaattttaaaa iiiissss iiiinnnn rrrraaaannnnggggeeee,,,, yyyyoooouuuu ccccaaaannnn
  150.             ssssppppeeeeeeeedddd uuuupppp pppprrrroooocccceeeessssssssiiiinnnngggg sssslllliiiigggghhhhttttllllyyyy bbbbyyyy uuuussssiiiinnnngggg tttthhhheeee
  151.             _a_l_S_e_t_L_i_m_i_t_i_n_g(_3_d_m) ccccaaaallllllll....
  152.  
  153.           ++++oooo IIIInnnn AAAALLLL 2222....0000,,,, tttthhhheeee pppprrrriiiinnnnttttiiiinnnngggg eeeerrrrrrrroooorrrr hhhhaaaannnnddddlllleeeerrrr iiiissss ooooffffffff bbbbyyyy
  154.             ddddeeeeffffaaaauuuulllltttt.... SSSSeeeeeeee _a_l_S_e_t_E_r_r_o_r_H_a_n_d_l_e_r(_3_d_m)....  NNNNooootttteeee tttthhhhaaaatttt AAAALLLL 1111....0000
  155.             pppprrrrooooggggrrrraaaammmmssss rrrreeeelllliiiinnnnkkkkeeeedddd wwwwiiiitttthhhh AAAALLLL 2222....0000 wwwwiiiillllllll aaaaccccqqqquuuuiiiirrrreeee tttthhhhiiiissss
  156.             bbbbeeeehhhhaaaavvvviiiioooorrrr....
  157.  
  158.           ++++oooo AAAALLLL 2222....0000 pppprrrroooovvvviiiiddddeeeessss _a_l_G_e_t_E_r_r_o_r_S_t_r_i_n_g(_3_d_m),,,, wwwwhhhhiiiicccchhhh rrrreeeettttuuuurrrrnnnnssss aaaa
  159.             tttteeeexxxxtttt ssssttttrrrriiiinnnngggg ccccoooorrrrrrrreeeessssppppoooonnnnddddiiiinnnngggg ttttoooo aaaannnnyyyy AAAALLLL eeeerrrrrrrroooorrrr ccccooooddddeeee.... TTTThhhhiiiissss
  160.             ssssiiiimmmmpppplllliiiiffffiiiieeeessss tttthhhheeee ttttaaaasssskkkk ooooffff hhhhaaaannnnddddlllliiiinnnngggg ffffuuuunnnnccccttttiiiioooonnnn ccccaaaallllllll ffffaaaaiiiilllluuuurrrreeeessss....
  161.  
  162.           ++++oooo IIIIRRRRIIIIXXXX 6666....3333 iiiinnnncccclllluuuuddddeeeedddd aaaa nnnneeeewwww vvvveeeerrrrssssiiiioooonnnn ooooffff _a_p_a_n_e_l,,,, tttthhhheeee aaaauuuuddddiiiioooo
  163.             ccccoooonnnnttttrrrroooollll ppppaaaannnneeeellll.... TTTThhhhiiiissss vvvveeeerrrrssssiiiioooonnnn ssssuuuuppppppppoooorrrrttttssss mmmmuuuullllttttiiiipppplllleeee iiiinnnnppppuuuutttt aaaannnndddd
  164.             oooouuuuttttppppuuuutttt ddddeeeevvvviiiicccceeeessss.... IIIInnnn IIIIRRRRIIIIXXXX 6666....5555 tttthhhhiiiissss hhhhaaaassss bbbbeeeeeeeennnn eeeennnnhhhhaaaannnncccceeeedddd ttttoooo
  165.             aaaalllllllloooowwww tttthhhheeee uuuusssseeeerrrr ttttoooo sssswwwwiiiittttcccchhhh bbbbeeeettttwwwweeeeeeeennnn ccccoooonnnnssssuuuummmmeeeerrrr----mmmmooooddddeeee aaaannnndddd
  166.             pppprrrrooooffffeeeessssssssiiiioooonnnnaaaallll----mmmmooooddddeeee ssssuuuubbbbccccooooddddeeee....
  167.  
  168.        5555....2222  _C_o_m_p_a_t_i_b_i_l_i_t_y__I_s_s_u_e_s
  169.  
  170.        This section lists the known compatibility issues between AL
  171.        2.0 and previous versions of the AL.
  172.  
  173.        AL 2.0 implements many old AL functions as wrappers around
  174.        new AL equivalents. Older AL programs relinked against AL
  175.        2.0 will thus automatically acquire some of the performance
  176.        improvements, enhancements and bug fixes in AL 2.0. However,
  177.        there are some caveats:
  178.  
  179.           +o AL 2.0 is a shared library. Previous versions of the AL
  180.             were statically linked. AL programs compiled or linked
  181.             under IRIX 6.3 cannot be run under previous versions of
  182.             IRIX.
  183.  
  184.           +o _A_L_w_r_i_t_e_s_a_m_p_s() and _A_L_r_e_a_d_s_a_m_p_s() are internally
  185.             implemented in terms of the newer _a_l_W_r_i_t_e_F_r_a_m_e_s() and
  186.             _a_l_R_e_a_d_F_r_a_m_e_s().  While this provides some performance
  187.             improvements, since the new functions are smaller and
  188.             faster, it removes the ability to read and write
  189.             partial sample frames on stereo ports.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.                                   - 4 -
  203.  
  204.  
  205.  
  206.           +o The default behavior for AL error handling is now
  207.             silence. Older versions of the AL would print messages
  208.             to the screen when an AL call failed. Unless you call
  209.             _a_l_S_e_t_E_r_r_o_r_H_a_n_d_l_e_r(_3_d_m) to install your own error
  210.             handler or to turn on printing messages, AL calls will
  211.             no longer print messages when they fail.
  212.  
  213.        Following are compatibility issues for all old applications
  214.        running on IRIX 6.5, even if not relinked with AL 2.0:
  215.  
  216.           +o The old AL sample-rate AL_RATE_INPUTRATE has different
  217.             semantics with the new audio driver. Setting the output
  218.             rate to AL_RATE_INPUTRATE will cause the rate on the
  219.             default output device to match the rate on the default
  220.             input device, if possible. But the output rate will not
  221.             track further changes to the input rate. Note also that
  222.             on some machines with multiple audio subsystems, it may
  223.             not be possible to match the two rates; the default
  224.             output device and default input device may not support
  225.             the same set of rates, or may not be able to access the
  226.             same timebase.
  227.  
  228.           +o Because the new driver maintains independent gain
  229.             values for each input source, changing the input source
  230.             now changes the input gain value. Old applications
  231.             which expect the gain value to remain constant across
  232.             input source changes may have issues under IRIX 6.5.
  233.  
  234.        5.3  _B_u_g__F_i_x_e_s
  235.  
  236.        This section lists the bugs fixed since the last release of
  237.        the IRIS Audio Library.  Some of the descriptions are
  238.        followed by a Silicon Graphics bug report number in the form
  239.        (SCR XXXX).
  240.  
  241.           +o A problem existed in previous releases of IRIX where a
  242.             rare race-condition could panic the system if a multi-
  243.             process application closed an audio port in one process
  244.             while it attempted to use the port in another process.
  245.             (SCR 334606)
  246.  
  247.           +o In four-channel mode, at sample-rates derived from
  248.             44.1kHz, under certain conditions the front and back
  249.             stereo pairs could become swapped. This has been fixed
  250.             (SCR 315007, 375810).
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.                                   - 5 -
  269.  
  270.  
  271.  
  272.        5.4  _K_n_o_w_n__P_r_o_b_l_e_m_s__a_n_d__W_o_r_k_a_r_o_u_n_d_s
  273.  
  274.        This section lists problems in the Audio Library software
  275.        and ways to work around them.
  276.  
  277.           +o When there is nothing physically connected to the
  278.             digital I/O jack, it is meaningless to set the system
  279.             sample rates in the following three ways:
  280.  
  281.                +o output sample rate set to match the input sample
  282.                  rate while using digital input as the system
  283.                  input.
  284.  
  285.                +o input sample rate set to the digital rate and the
  286.                  output rate set to match the input rate.
  287.  
  288.                +o input sample rate set to the digital rate and the
  289.                  output rate set to the digital input rate.
  290.  
  291.                +o When the system is placed in one of these states,
  292.                  the behavior cannot be predicted. Performing any
  293.                  of the actions listed above should be avoided by
  294.                  application programs.
  295.  
  296.        5.5  _P_r_o_g_r_a_m_m_i_n_g__E_x_a_m_p_l_e_s
  297.  
  298.        The _d_m_e_d_i_a__d_e_v._s_r_c._e_x_a_m_p_l_e_s subsystem contains several
  299.        source code examples for programming with the Audio Library.
  300.        The source code is available in the directory
  301.        /_u_s_r/_s_h_a_r_e/_s_r_c/_d_m_e_d_i_a/_a_u_d_i_o.
  302.  
  303.        The _d_m_e_d_i_a__d_e_v._s_r_c._t_o_o_l_s subsystem includes the source code
  304.        for the standard aaaauuuuddddiiiiooooppppaaaannnneeeellll((((1111)))) and ssssoooouuuunnnnddddppppllllaaaayyyyeeeerrrr((((1111)))) tools
  305.        which are shipped with IRIX 6.2 and later. The source code
  306.        is installed in the directories
  307.        /_u_s_r/_s_h_a_r_e/_s_r_c/_d_m_e_d_i_a/{_a_u_d_i_o_p_a_n_e_l,_s_o_u_n_d_p_l_a_y_e_r}.
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.